---
sidebar_position: 101
title: Contributing
---

# Contributing

**Contributions are welcome!**

## Contributionut

### Add Core JavaScript APIs

The DeviceScript [core js library](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects) is not complete; but it is possible to fill the gaps
as needed. The requests are tracked by the [core js issue label](https://github.com/microsoft/devicescript/issues?q=is%3Aissue+is%3Aopen+label%3A%22core+js%22).

You will need a local development setup for these tasks.

If you want to add a new function:

-   find the corresponding function definition in one of the `lib/es....d.ts` file.
-   copy the definition in the corresponding interface in `packages/core/src/corelib.d.ts`
-   implement the function in the implementation file of the type (see `packages/core/src/array.ts` for example).
    If you are adding a new file, make sure to import it in `packages/core/src/index.ts`.
-   add test cases in the corresponding test file under `devs/run-tests`
-   build and test
-   create a pull request and go!

If you want to add a new Type, we currently have a limitation with the `core` package and you will need to add it to the `runtime` package:s

-   implement the class in the implementation file of the type (see `packages/runtime/src/map.ts` for example).
    If you are adding a new file, make sure to import it in `packages/runtime/src/map.ts`.
-   add test cases in the corresponding test file under `packages/runtime/src/main.ts`
-   build and test
-   create a pull request and go!

### Samples

Documentation samples are located under `website/docs/samples`.
Each `.mdx` file contains a single self-contained sample.

It is typically easiest to develop a sample in a dedicate `.ts` file
to leverage the editor's features, and then copy it to the `.mdx` file.

To run the docs locally, run `yarn docs`. This will launch the docusaurus development server
and refresh the documentation page on each edit.

If your sample requires multiple files, such as images,

-   create a folder with the same name as the `.mdx` file
-   move your `.mdx` file and rename it to `index.mdx`
-   add a `_category_.json` file with the front matter

```json
{
    "label": "Samples",
    "position": 3
}
```

### Documenting/patching console output

To add new substitions from console output message to pretty text + URL, do the following.

The `website/docs/developer/errors.mdx` gets parsed by builderrors.mjs.
The hash of the H2 titles is the console log look up key (replacing - with spaces) and the H2 text will replace that key + URL.

    loopback rx ovf --> Loopback buffer overflow (....#loopback-rx-ovf)

### Adding Builtin Packages

Adding a new package is more advanced scenario and most likely we should have a discussion prior to start this work. You are welcome to publish packages under your account in npm.

> A good question to start with: Do we need a new builtin package or should it be a new npm package?

Generally, search for `@devicescript/gpio` within the workspace. The main places that need updating is:

-   this file, `website/docs/developer/packages.mdx`
-   list in `plugin/src/plugin.ts`
-   list in `devs/run-test/allcompile.ts`

After adding a new packages, run `yarn` at the top-level to update workspace links,
followed by the usual `yarn build`.


## Local development

The development requirement will vary (widely) depending
on which part of DeviceScript you want to work on.

Using Visual Studio Code is strongly recommended.

### Repository structure

This repository contains:

-   [jacdac-c submodule](https://github.com/microsoft/jacdac-c), including sources for Jacdac client libraries and DeviceScript VM
-   `compiler/` - sources for DeviceScript compiler
-   `runtime/devicescript-vm/` - glue files to build DeviceScript VM as WASM module using [emscripten](https://emscripten.org/); `vm/dist/` contain pre-built files
-   `packages` - builtin packages and sample project (`packages/sampleprj`)
-   `runtime/posix/` - implementation of Jacdac SDK HAL for grown-up POSIX-like operating systems (as opposed to embedded platforms)
-   `vscode` - Visual Studio Code extension
-   `website` - docusaurus documentation side

### Compiler, runtime and command line

You can use the devcontainer to build. The instructions are tested for a Unix terminal.

If you want to build locally you need to install node.js. After cloning, the repo run

```bash
yarn setup
```

To run a watch build and the docs, run

```
nvm use 18
yarn dev
```

-   start `jacdac devtools` (the npm version) and let it run
-   open this folder in VSCode; use "Reopen in Container" if needed
-   start Terminal in VSCode
-   run `yarn install`
-   run `yarn build`
-   run `yarn devs run devs/samples/something.ts` - this will execute given DeviceScript program using the WASM binary

If you want to develop the runtime (as opposed to compiler or website), you will also need
GNU Make, C compiler, and [emscripten](https://emscripten.org/docs/getting_started/downloads.html).
Once you have it all:

-   run `make native` to compile using native C compiler
-   run `yarn devs crun devs/samples/something.ts` - this will execute given DeviceScript program using the POSIX/native binary
-   run `./runtime/built/jdcli 8082` - this will run the POSIX/native DeviceScript server, which can be accessed from the devtools dashboard
-   run `make em` to compile using emscripten

### Visual Studio Extension

Open the Debug view in VSCode and run the `VSCode Extension` configuration. This will launch a new VSCode instance with the extension loaded. A build is automatically triggered before launch VSCode.

### Building packages

Similar to working on the Visual Studio Code extension, lunch the `VSCode Extension` debugger configuration. This will launch a new VSCode instance with the extension loaded.
It should also open the `packages` folder which will allow you to work on the built-in packages.

### Documentation

Run `yarn docs` and edit any markdown file in the `website/docs` folder. The changes should be automatically picked up and rendered by docusaurus.

## Release process

Run `yarn bump` (or `make bump`). Alternatively, edit `img_version_patch` in `bytecode/bytecode.md` and push.

The cloud build will rebuild and check-in the VM, update version numbers in all `package.json` files, and publish them.

If you bump minor, you need to also bump the firmware repos:

-   go to each firmware repo (https://github.com/microsoft/devicescript-esp32, https://github.com/microsoft/devicescript-pico, https://github.com/microsoft/devicescript-stm32)
-   update the `devicescript` submodule
-   run

```bash
make bump
```

## Legal

This project welcomes contributions and suggestions. Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
